home *** CD-ROM | disk | FTP | other *** search
/ Resource for Source: C/C++ / Resource for Source - C-C++.iso / misc_src / grepbrws / readme.txt < prev    next >
Encoding:
Text File  |  1995-11-01  |  8.0 KB  |  244 lines
  1. GrepBrowser Documentation
  2.  
  3. 9/15/93, Wednesday
  4.  
  5. Windows Tech Journal
  6. OOP Alley, October 1993
  7. Greg Voss
  8.  
  9. Article Title:      What I Learned in Auto Shop
  10. Subject:            Direct Manipulation Tools for Windows
  11.                     Browsers for Source Code Management
  12.  
  13. Example Programs:   GrepBrowser
  14.                     grep.exe
  15.                     sed.exe
  16.  
  17. Tools used to       GrepBrowser
  18. build exe's:            Smalltalk/V Windows 2.0, Windows 3.1
  19.                         Borland Resource Workshop
  20.                         Borland C++ 3.1
  21.                     grep and sed
  22.                         Borland C++ 3.1
  23. ============================================================
  24.  
  25. This month's posting is an executable program in binary
  26. form.  The intent is to show a browser that can be
  27. used as a programming tool as well as to show what
  28. a Smalltalk program looks like when distributed
  29. without source.  I have used this browser for a little
  30. over a year to develop and manage source code for large
  31. C, C++, and Lisp projects.
  32.  
  33. This program is essentially the same as the program
  34. produced by filing in (compiling) the source posted
  35. last month.  I've also posted binary versions of
  36. grep and sed that make it easy to massage output
  37. from various compilers into a format that can be
  38. fed into GrepBrowser.  If you already have versions
  39. of grep and sed, you'll probably want to use your
  40. own as these support only bare bones flag options.
  41. If you use Borland grep, you'll still need sed to
  42. massage the output as Borland output is not standard
  43. Unix (i.e. not designed to be the middle component of
  44. a pipe sequence).
  45.  
  46.  
  47. Installation
  48. ============
  49.  
  50. If you have a standard bin or tool directory, copy
  51. all the exe and dll files to that directory.  If
  52. not make a new directory and copy the files there.
  53. This directory must be in your path specifcation
  54. so edit autoexec.bat if you make a new directory.
  55.  
  56.  
  57. Using GrepBrowser
  58. =================
  59.  
  60. GrepBrowser must be invoked with one argument
  61.  
  62.     gb file
  63.  
  64. The file is called a 'grep list' file and is
  65. a text file in which each line specifies where
  66. to find text patterns matched by grep.  The
  67. grep list format is shown below.  The most
  68. convenient way to use GrepBrowser is with
  69. Windows' Program Manager. For example, assume
  70. that gb.exe is installed and you have created
  71. a grep list file called tag.grp in the directory
  72. c:\work\compiler.  Create a new program object
  73. in the Program Manager and fill in the fields
  74. as follows.
  75.  
  76.     Description:        GrepBrowser on tag.grp
  77.     Command Line        gb.exe tag.grp
  78.     Working Directory   c:\work\compiler
  79.     Shortcut Key        (not required)
  80.  
  81. You can fill in a short cut key if you want.
  82. When you press OK in the Program Item Properties
  83. dialog, the specifications are recorded and
  84. a little nerd icon should appear in the window.
  85. Now double click on the nerd to invoke GrepBrowser.
  86.  
  87. Note that you do not have to specify a working
  88. directory if you give a fully qualified pathname
  89. for the grep list file:
  90.  
  91.     gb.exe c:\work\compiler\tag.grp
  92.  
  93. Technically, the file argument is not required.
  94. However, once a GrepBrowser window is open,
  95. there is no convenient way to change the file
  96. used for the grep list.  You can edit the file
  97. while in the Browser and update the grep list
  98. from a modified version of the same file.  However
  99. you can not select a new grep list file except
  100. from the command line.  This restriction is
  101. easy to modify (see September source code)
  102. but I decided to take time to develop a
  103. more sophisticated command line syntax before
  104. adding menu commands.  There is also some
  105. potential confusion in the menu interface.
  106. Now, the open command will open a regular text
  107. file for editing, so 'Open' is not available
  108. to indcate desire to change the grep list file.
  109.  
  110. In practice, the current command line syntax
  111. is convenient.  I tend to have a single
  112. grep list file devoted to a given project.
  113. I put tags in the file as markers for grep to
  114. search for.  The only exeption is when I want to
  115. quickly look for a variety of patterns in a set
  116. of files.  In such a case I use file names for
  117. grep output like 00.grp and 01.grp and put
  118. matching program items in the Program Manager.
  119.  
  120. You can always run GrepBrowser from the
  121. 'File / Run' command in Program Manager.  You
  122. can also create an association for 'grp' files
  123. in the File Manager which ties files ending
  124. in '*.grp' to gb.exe.  Then a double click on
  125. a grp file in the File Manager will automatically
  126. invoke a GrepBrowser on the selected file.
  127. (Another example of a Browser using direct
  128. manipulation).
  129.  
  130.  
  131.  
  132. GrepList Format
  133. ===============
  134.  
  135. Each line of the grep list file specifies a
  136. file name, a line number, and text, just like
  137. standard output from grep when the -n flag is used
  138. and more than one file is searched.  It's convenient
  139. to think of each line as a record with three fields or
  140. to think of each line as a specification for
  141. a GrepObject--an actual class in the source.
  142.  
  143. The following output from grep is typical:
  144.  
  145.     input.lsp:18:  (defclass c-input-class ()
  146.     parse.lsp:10:  (defclass c-parser-class ()
  147.     scan.lsp:72:   (defclass c-scanner-class ()
  148.     symbol.lsp:11: (defclass lex-symbol ()
  149.     symbol.lsp:27: (defclass symbol-table ()
  150.     test.lsp:1:    (defclass c-input-class ()
  151.  
  152. In this case the goal was to search for all
  153. class definitions in a set of Lisp files used
  154. to build a C compiler.  The actual grep command 
  155. line was
  156.  
  157.     grep -n defclass *.lsp >class.grp
  158.  
  159. Now a GrepBrowser can be opened
  160.  
  161.     GrepBrowser \work\compiler\class.grp
  162.  
  163. Or you could set up a Program Item in the
  164. Windows Program Manager as follows:
  165.  
  166.     Description:        GrepBrowser on Parser Classes
  167.     Command Line        gb.exe class.grp
  168.     Working Directory   c:\work\compiler
  169.     Shortcut Key        (not required)
  170.  
  171.  
  172. Searching a Single File
  173. =======================
  174.  
  175. Note that if grep is used on only one file,
  176. the output will not include the file name.
  177. For example
  178.  
  179.    grep -n grep notes.txt
  180.  
  181. produces
  182.  
  183.     21:    GrepBrowser [grepFile] [searchFile]
  184.     27:(e.g. grepFile: class.grp searchFile: app.h)
  185.     52:grepFile from which the browser should reinitialize
  186.     57:a new grepFile and reinitializing the grepList from
  187.     131:during the parse of the grepList.  The answer
  188.     143:original specification so that modified grepLists
  189.  
  190.  
  191. Currently GrepBrowser can't handle lines which do not
  192. include file names.  The mechanisms are in place to
  193. do this and a future release will support this feature.
  194. In the mean time, just give a dummy (non-existent file)
  195. argument to grep:
  196.  
  197.     grep -n grep notes.txt xxxx >out.grp
  198.  
  199. produces
  200.  
  201.     notes.txt:21:    GrepBrowser [grepFile] [searchFile]
  202.     notes.txt:27:(e.g. grepFile: class.grp searchFile: app.h)
  203.     notes.txt:52:grepFile from which the browser should reinitialize
  204.     notes.txt:57:a new grepFile and reinitializing the grepList from
  205.     notes.txt:131:during the parse of the grepList.  The answer
  206.     notes.txt:143:original specification so that modified grepLists
  207.  
  208. The error message 'GREP.EXE: couldn't open xxxx' 
  209. is sent to stderr (standard error device), not 
  210. to standard output, so it will not interfere 
  211. when output is redirected to out.grp.
  212.  
  213.  
  214. Converting Borland C++ Output
  215. =============================
  216.  
  217. You can use grep and sed in combination
  218. to convert error and warning messages
  219. printed by Borlandc C++ into a format that
  220. can be used by GrepBrowser.  The basic
  221. idea is to direct output to a file
  222. (e.g. bcc.err) and then invoke a batch
  223. file which reads this file and filters
  224. it.  The file bcc2grep.sed contains
  225. two regular expression editing commands:
  226. one for error messages and one for 
  227. warnings.  An example C++ program
  228. (ex1.cpp) will genrate the errors found
  229. in bcc.err.  Both this file and the
  230. converted file created by bcc2grep.bat
  231. are provided with the distribution files
  232. for study.  The following files are all
  233. related to conversion of BC++ output into
  234. a grep list file suitable for GrepBrowser.
  235.  
  236.     bcc2grep.bat
  237.     ex1.cpp
  238.     bcc.err
  239.     bcc.grp
  240.     bcc2grep.sed
  241.  
  242.  
  243. OOP, OOP, and away.
  244.